/*
 * DelegationConstants.java Version-1.4, 2002/11/22 09:26:10 -0800 (Fri)
 * ECTF S.410-R2 Source code distribution.
 *
 * Copyright (c) 2002, Enterprise Computer Telephony Forum (ECTF),
 * All Rights Reserved.
 *
 * Use and redistribution of this file is subject to a License.
 * For terms and conditions see: javax/telephony/media/LICENSE.HTML
 * 
 * In short, you can use this source code if you keep and display
 * the ECTF Copyright and the License conditions. The code is supplied
 * "AS IS" and ECTF disclaims all warranties and liability.
 */

package javax.telephony.media;


/**
 * Defines the Constants used in the Delegation interface.
 *
 * @author  Jeff Peck
 * @since   JTAPI-1.4
 */
public interface DelegationConstants extends MediaServiceConstants {

    /** Special tag value to invoke destroy  processing. */
    String tag_DestroyRequest = "Group_ECTF_DestroyRequest";

    /** Special tag to catch no tag.
     * Means <tt>delegate</tt> will return with <tt>(isOwner()==false)</tt>.
     * <p>
     * It is an error to use this as a return tag;
     * the result is undefined.
     */
    String tag_CatchNone = "Group_ECTF_NeverReturn";

    /** Special tag to catch no tag.
     * Means <tt>delegate</tt> will return with <tt>(isOwner()==false)</tt>.
     * <p>
     * It is an error to use this as a return tag;
     * the result is undefined.
     */
    String tag_NeverReturn = "Group_ECTF_NeverReturn";

    /** Special tag value to return to most recent caller 
     * of delegateToService. 
     */
    String tag_NormalReturn = "Group_ECTF_NormalReturn";

    /** Special tag to request that this MediaService be removed
     * as the owner or potential owner.  
     * This special tag value ("<tt>Group_ECTF_RemoveSession</tt>")
     * should <b>not</b> be used by applications.  Applications that use
     * this tag may get unexpected and non-portable results.
     * It is defined for internal use in <tt>releaseToService</tt> 
     * and <tt>releaseDelegated</tt>.
     */
    String tag_RemoveSession = "Group_ECTF_RemoveSession";

    /** Special tag value indicating that the server has
     * lost connection with the current owner.
     */
    String tag_SessionDeath = "Group_ECTF_SessionDeath";

    // note: this is not defined in S.100-R2
    /** Special tag to catch any and all tags. */
    String tag_CatchAll = "Group_ECTF_CatchAll"; 

    /** Special tag when the MediaGroup was retrieved from this MediaService. 
     * Return value from getReturnTags().
     */
    // in the stated case, tags should be (Symbol cause).toString()
    // String tag_RetrieveRequest = "Group_ECTF_RetrieveRequest";

    /**
     * Non-Trans event generated by delegateToService.
     * Delievered to {@link DelegationListener#onDelegated}.
     */
    Symbol ev_Delegated		= ESymbol.Group_HandOff;   // onDelegated

    /**
     * Qualifier when delegateToService completes because
     * MediaGroup was returned to this MediaService.
     * The return tag is available using <tt>DelegationEvent.getReturnTag();</tt> 
     * <p>
     * This MediaService is bound.
     */
    Symbol q_Returned = ESymbol.Group_Returned;

    /**
     * Qualifier when delegateToService completes because
     * MediaGroup was retrieved by this or some older owner.
     * <p>
     * If retrieved by some older owner, then this MediaService is unbound.
     */
    Symbol q_Retrieved = ESymbol.Group_Retrieved;

    /**
     * Qualifier when delegateToService completes because
     * this MediaService executed releaseDelegated.
     * <p>
     * This MediaService is unbound.
     */
    Symbol q_Removed= ESymbol.Group_Returned; // arbitrary Symbol...

    /**
     * Qualifier when delegateToService completes because
     * MediaGroup was released to older owner. 
     * <br> or when it was retrieved by older owner.
     * <p>
     * If MediaGroup was released, then <tt>getRetrieveCause()</tt> is v_released
     * and <tt>getReturnTag()</tt> is the Tag [which was not caught by this MediaService]
     * <p>
     * If MediaGroup was retrieved, then <tt>getRetrieveCause()</tt> is
     * the Symbol supplied to <tt>retrieve(Symbol cause)</tt>
     * <p>
     * This MediaService is unbound.
     */
    Symbol q_Released = ESymbol.Group_Unwind;

    /**
     * Value of getRetrieveCause() when 
     * MediaGroup was released to older owner. 
     */
    Symbol v_Released = ESymbol.Group_Unwind;
}
